---
type: tutorial
title: 创建你的第一个 Astro 项目
description: |-
  教程：搭建你的 Astro 博客 —
   为 Astro 教程创建一个新项目并准备编写代码
---
import Checklist from '~/components/Checklist.astro';
import Box from '~/components/tutorial/Box.astro';
import InstallGuideTabGroup from '~/components/TabGroup/InstallGuideTabGroup.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import PreCheck from '~/components/tutorial/PreCheck.astro';
import { Steps } from '@astrojs/starlight/components';
import Badge from "~/components/Badge.astro"

<PreCheck>
  - 运行 `create astro` 安装向导来创建一个新的 Astro 项目
  - 以开发 (dev) 模式启动 Astro 服务器
  - 在浏览器中查看你网站的实时预览
</PreCheck>

## 启动 Astro 设置向导

创建新 Astro 站点的首选方法是通过我们的 `create astro` 设置向导。

<Steps>
1. 在终端的命令行中，使用你首选的包管理器运行以下命令：

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # 使用 npm 创建新项目
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # 使用 pnpm 创建新项目
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # 使用 yarn 创建新项目
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>

2. 输入 `y` 以安装 `create-astro`。

3. 当提示你想要在哪里创建你的新项目时，输入文件夹的名称来为你的项目创建一个新目录，例如：`./tutorial`

    :::note
    新的 Astro 项目只能在一个完全空的文件夹中创建，因此请为你的文件夹选择一个尚不存在的名称！
    :::

4. 你会看到一个简短的入门模板列表。使用方向键（上下键）导航到 minimal（空白）模板，然后按下回车键（Enter）确认你的选择。

5. 当提示询问你是否要安装依赖项时，输入 `y`。

6. 当提示询问你是否要初始化一个新的 Git 仓库时，输入 `y`。
</Steps>

安装向导完成后，你不再需要此终端。你现在可以打开 VS Code 继续。

## 在 VS Code 中打开你的项目

<Steps>
7. 打开 VS Code。系统将提示你打开一个文件夹。选择你在安装向导期间创建的文件夹。

8. 如果这是你第一次打开 Astro 项目，你应该会看到一条通知，询问你是否要安装推荐的扩展。点击查看推荐扩展，选择 [Astro 语言支持](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)。这将为你的 Astro 代码提供语法提示和自动代码补全功能。

9. 打开 VS Code 终端，可以看到类似如下提示：

    ```sh
    user@machine:~/tutorial$
    ```

    :::tip[快捷键]
    按 <kbd>Ctrl + J</kbd>（macOS: <kbd>Cmd ⌘ + J</kbd>）在 VS Code 中打开终端。
    :::
</Steps>

你现在可以使用 VS Code 的内置的终端，而不是计算机自带的终端程序。

## 在开发模式下运行 Astro

为了实时预览项目，你需要在开发 (dev) 模式下运行 Astro。

### 启动开发服务

<Steps>
10. 通过在 VS Code 的终端中输入以下命令来启动 Astro 开发服务：

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm run dev
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm run dev
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn run dev
      ```
      </Fragment>
    </PackageManagerTabs>

    现在你应该能在终端中看到 Astro 正在以开发模式运行的提示信息。🚀
</Steps>

## 查看你网站的预览

你的项目文件包含显示 Astro 网站所需的所有代码，但浏览器负责将你的代码显示为网页。

<Steps>
11. 点击终端窗口中的 `localhost` 链接，查看 Astro 网站的实时预览！

     （如果端口 4321 可用，Astro 默认使用 `http://localhost:4321`。）

     以下是 Astro“初始项目”入门网站在浏览器预览中的样子：

     ![顶部带有 Astro 字样的空白白页。](/tutorial/minimal.png)

</Steps>

:::tip[Astro 开发服务器]

当 Astro 服务器以开发模式运行时，你将**无法**在终端窗口中运行命令。相反，此窗格会在你预览站点时为你提供反馈。

你可以随时停止开发服务器并通过在终端中键入 <kbd>Ctrl + C</kbd> 返回到命令提示符。

有时开发服务器会在你工作时自行停止。如果你的实时预览停止工作，请返回终端并通过键入 `npm run dev` 重新启动开发服务器。
:::

<Box icon="check-list">

## 任务清单

<Checklist>
- [ ] 我可以创建一个新的 Astro 项目。
- [ ] 我可以启动 Astro 开发服务器。
</Checklist>
</Box>

### 相关资源

- <p>[Visual Studio Code 入门](https://code.visualstudio.com/docs/introvideos/basics) <Badge class="neutral-badge" text="外部链接" /> — 用于安装、设置和使用 VS Code 的视频教程</p>
